Node / ReticulumProjects / MeshChatX.git / files / docs / en / identity-and-security.md

Displaying Rendered • View raw • Download

MeshChatX separates cryptographic identities, network security, and optional privacy controls. This page summarises how they interact.

Each identity is a Reticulum key pair with its own:

• SQLite database and LXMF router directory

• Settings in the T383838config table via T383838ConfigManager

• Storage path under T383838storage/identities/<identity_hash>/

Create, import, or switch identities from Identities. Only one identity is active in the UI at a time. Switching runs a teardown path so routers and managers do not leak state.

Shared resources include the Reticulum process and interface configuration in T383838~/.reticulum unless you override paths.

MeshChatX tracks announces for aspects such as:

Announce records store signal metadata and parsed app data for display names and icons.

Optional HTTP basic authentication is enabled with T383838--auth or T383838MESHCHAT_AUTH=true. Sessions use encrypted cookies. Mutating API requests require CSRF tokens.

Access attempts are logged. Repeated failures can trigger lockout when auth is enabled.

Reset a forgotten password with T383838--reset-password or T383838MESHCHAT_RESET_PASSWORD=true, then set a new password in the UI.

T383838MESHCHAT_DEMO_MODE=1 (or T383838--demo) enables a public showcase profile: privacy mode on, plugins off, no outbound announces, and a default-deny HTTP mutation policy with mesh send blocked. Status reports T383838demo_mode: true.

When T383838MESHCHAT_ALTCHA_ENABLED=1, login and setup require a valid ALTCHA proof-of-work payload (widget v3, server challenges use T383838PBKDF2/SHA-256 by default). Set T383838MESHCHAT_ALTCHA_HMAC_KEY to a long random secret on the server. Optional T383838MESHCHAT_ALTCHA_COST tunes PoW difficulty. The widget loads from the bundled T383838altcha npm package and fetches challenges from T383838/api/v1/auth/altcha/challenge.

T383838MESHCHAT_AUTH_PAGE_HINT sets optional plain text on the login page (independent of demo mode). Demo Docker compose defaults to username and password hints for the showcase account.

T383838MESHCHAT_AUTH_BYPASS=1 skips session auth for local testing only. Do not use it on internet-facing deployments.

• HTTPS and WSS are on by default.

• Self-signed certificates are generated per identity when custom PEM files are missing.

• Pass T383838--ssl-cert and T383838--ssl-key for managed certificates.

• Use T383838--no-https only on trusted loopback setups.

Electron loads the UI from the local HTTPS origin served by the embedded backend.

T383838app_security_settings can restrict which client IPs may use the web UI. Combine with auth when exposing the service beyond localhost.

Privacy mode blocks outbound HTTP from MeshChatX features that would otherwise call the public internet. Translation and similar tools respect this flag.

Privacy mode does not disable Reticulum mesh traffic. It limits clearnet fetches from the app itself.

On Linux, MeshChatX can enable two complementary in-process sandboxes when supported:

• Landlock restricts filesystem paths the backend may use. User-local pipx tools (for example Argos Translate under T383838~/.local) need explicit read and sometimes write roots. See Linux sandboxing in Platform guides.

• Seccomp-BPF installs a syscall denylist (via libseccomp) that blocks kernel-admin and related calls a mesh client does not need

Both auto-enable when available and fall back to a no-op when the platform, kernel, or libraries cannot support them. Override with:

• T383838MESHCHAT_LANDLOCK=0 or T3838381

• T383838MESHCHAT_SECCOMP=0 or T3838381

Android never enables these in-process sandboxes (the Android app seccomp policy already constrains the process, and Landlock syscalls are blocked there).

See Linux sandboxing in Platform guides for optional Firejail and Bubblewrap wrappers around the host install.

Use Blocked for specific destination hashes. Combine with sieve filters, message blocklists, and LXMF stamp policies described in LXMF messaging.

Database backups land in T383838database-backups/. Before a schema upgrade, MeshChatX writes a T383838backup-pre-migrate-v*-to-v*.zip in that folder unless T383838MESHCHAT_SKIP_PRE_MIGRATE_BACKUP=1. After a successful migration it runs T383838PRAGMA quick_check and keeps the five newest pre-migrate zips (override with T383838MESHCHAT_PRE_MIGRATE_BACKUP_KEEP, T3838380 disables pruning). If the stored schema version is newer than this build supports, startup refuses to migrate. Only one process should use a given identity storage directory at a time (storage lock). Roll back by restoring a backup zip and running an older MeshChatX build. Export snapshots from About or the API. Electron crash recovery can offer restore when integrity checks fail.

CLI examples:

T282828

Startup integrity verification runs in packaged Electron builds and can be triggered from the backend. Failed checks surface recovery options instead of silently corrupting data.

Packaged plugins may include a Reticulum Signature (T383838.rsg) over a canonical ZIP payload (sorted paths, fixed 1980-01-01 mtimes, signature file excluded). MeshChatX plugin signing writes T383838meshchatx.plugin.rsg and WASM sections T383838meshchatx.plugin / T383838meshchatx.files / T383838meshchatx.signature.

Policy:

• Unsigned packages are allowed

• Present but invalid signatures hard-block install

• Valid signers can be added to a user trusted-publishers list (ignored if the list file is tampered outside MeshChatX)

• Installed plugin trees get an integrity hash, on-disk changes disable the plugin as tampered

Sideband Python plugins are opt-in via a master danger switch. They are not ZIP-permission gated. Optional per-file T383838.py.rsg signatures are verified over script bytes.

T282828

Avoid exposing port 8000 directly to the internet without a reverse proxy, strong auth, and network-level filtering. MeshChatX is designed as a personal or small-team operator console, not a multi-tenant public website.

On shared computers, use separate OS user accounts or separate T383838--storage-dir values so SQLite databases and identity files do not overlap.

• Architecture and design for session and API details

• Installation and setup for CLI security flags

• Reticulum manual cryptography chapters for identity math